IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/librw/RWTIsvDlist.z/RWTIsvDlist

Text File | 1998-10-30 | 14.6 KB | 463 lines

RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWTIsvDlist<T> - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/tidlist.h>



              RWTIsvDlist<T> list;




DDDDeeeessssccccrrrriiiippppttttoooonnnn
     Class RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt<<<<TTTT>>>> is a class that implements intrusive doubly-linked
     lists. An intrusive list is one where the member of the list must inherit
     from a common base class, in this case RRRRWWWWIIIIssssvvvvDDDDlllliiiinnnnkkkk.  The advantage of such
     a list is that memory and space requirements are kept to a minimum.  The
     disadvantage is that the inheritance hierarchy is inflexible, making it
     slightly more difficult to use with an existing class.  Class
     RRRRWWWWTTTTVVVVaaaallllDDDDlllliiiisssstttt<<<<TTTT>>>> is offered as an alternative, non-intrusive, linked list.
     See Stroustrup (1991; Section 8.3.1) for more information about intrusive
     lists.  NNNNooootttteeee tttthhhhaaaatttt wwwwhhhheeeennnn yyyyoooouuuu iiiinnnnsssseeeerrrrtttt aaaannnn iiiitttteeeemmmm iiiinnnnttttoooo aaaannnn iiiinnnnttttrrrruuuussssiiiivvvveeee lllliiiisssstttt,,,, tttthhhheeee
     aaaaccccttttuuuuaaaallll iiiitttteeeemmmm (not a copy) is inserted.  Because each item carries only one
     link field, the same item cannot be inserted into more than one list, nor
     can it be inserted into the same list more than once.


EEEExxxxaaaammmmpppplllleeee
              #include <rw/tidlist.h>
          #include <rw/rstream.h>
          #include <string.h>


              struct Symbol : public RWIsvDlink {



                char name[10];
            Symbol( const char* cs)  {
              strncpy(name, cs, sizeof(name)); name[9] = ' ';
            }
          };


              void printem(Symbol* s, void*) { cout << s->name << endl; }
          main()  {








                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))



                RWTIsvDlist<Symbol> list;
            list.insert( new Symbol("one") );
            list.insert( new Symbol("two") );
            list.prepend( new Symbol("zero") );


                list.apply(printem, 0);



                list.clearAndDestroy();  // Deletes the items inserted into
                                     // the list
            return 0;
          }


     PPPPrrrrooooggggrrrraaaammmm OOOOuuuuttttppppuuuutttt::::

              zero
          one

PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
     two



              RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt();


     Constructs an empty list.

              RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt(T* a);


     Constructs a list with the single item pointed to by aaaa in it.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              void
          aaaappppppppeeeennnndddd(T* a);


     Appends the item pointed to by aaaa to the end of the list.

              void
          aaaappppppppllllyyyy(void (*applyFun)(T*, void*), void* d);


     Calls the function pointed to by aaaappppppppllllyyyyFFFFuuuunnnn to every item in the
     collection.  This must have the prototype:






                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))



              void  yyyyoooouuuurrrrFFFFuuuunnnn(T* item, void* d);





     The item will be passed in as argument iiiitttteeeemmmm.  Client data may be passed
     through as parameter dddd.

              T*
          aaaatttt(size_t i) const;


     Returns the item at index iiii.  The index iiii must be between zero and the
     number of items in the collection less one, or an exception of type
     TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.

              void
          cccclllleeeeaaaarrrr();


     Removes all items from the list.

              void
          cccclllleeeeaaaarrrrAAAAnnnnddddDDDDeeeessssttttrrrrooooyyyy();


     Removes aaaannnndddd ccccaaaallllllllssss ddddeeeelllleeeetttteeee for each item in the list.  Note that this
     assumes that each item was allocated off the heap.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(RWBoolean (*testFun)(const T*, void*),void* d)
                   const;


     Returns TTTTRRRRUUUUEEEE if the list contains an item for which the user-defined
     "tester" function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE .  The tester
     function must have the prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssssRRRReeeeffffeeeerrrreeeennnncccceeee(const T* a) const;





                                                                        PPPPaaaaggggeeee 3333






RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))



     Returns TTTTRRRRUUUUEEEE if the list contains an item with the address aaaa.

              size_t
          eeeennnnttttrrrriiiieeeessss() const;


     Returns the number of items currently in the list.

              T*
          ffffiiiinnnndddd(RWBoolean (*testFun)(const T*, void*),void* d) const;


     Returns the first item in the list for which the user-defined "tester"
     function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE.  If there is no such item,
     then returns nnnniiiillll.  The tester function must have the prototype:

                 RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              T*
          ffffiiiirrrrsssstttt() const;


     Returns (but does not remove) the first item in the list, or nnnniiiillll if the
     list is empty.

              T*
          ggggeeeetttt();


     Returns aaaannnndddd rrrreeeemmmmoooovvvveeeessss the first item in the list, or nnnniiiillll if the list is
     empty.

              size_t
          iiiinnnnddddeeeexxxx(RWBoolean (*testFun)(const T*, void*),void* d) const;


     Returns the index of the first item in the list for which the user-
     defined "tester" function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE.  If there
     is no such item, then returns RRRRWWWW____NNNNPPPPOOOOSSSS.  The tester function must have the
     prototype:

                 RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);






                                                                        PPPPaaaaggggeeee 4444






RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              void
          iiiinnnnsssseeeerrrrtttt(T* a);


     Appends the item pointed to by aaaa to the end of the list.  This item
     cannot be inserted into more than one list, nor can it be inserted into
     the same list more than once.

              void
          iiiinnnnsssseeeerrrrttttAAAAtttt(size_t i, T* a);


     Insert the item pointed to by aaaa at the index position iiii.  This position
     must be between zero and the number of items in the list, or an exception
     of type TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.  The item cannot be inserted into more
     than one list, nor can it be inserted into the same list more than once.

              RWBoolean
          iiiissssEEEEmmmmppppttttyyyy() const;


     Returns TTTTRRRRUUUUEEEE if there are no items in the list, FFFFAAAALLLLSSSSEEEE otherwise.

              T*
          llllaaaasssstttt() const;


     Returns (but does not remove) the last item in the list, or nnnniiiillll if the
     list is empty.

              size_t
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffff(RWBoolean (*testFun)(const T*, void*),void* d)
                        const;


     Traverses the list and returns the number of times for which the user-
     defined "tester" function pointed to by tttteeeessssttttFFFFuuuunnnn returned TTTTRRRRUUUUEEEE .  The
     tester function must have the prototype:

                 RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd



                                                                        PPPPaaaaggggeeee 5555






RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))



              size_t
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffffRRRReeeeffffeeeerrrreeeennnncccceeee(const T* a) const;


     Returns the number of times which the item pointed to by aaaa occurs in the
     list.  Because items cannot be inserted into a list more than once, this
     function can only return zero or one.

              void
          pppprrrreeeeppppeeeennnndddd(T* a);


     Prepends the item pointed to by aaaa to the beginning of the list.

              T*
          rrrreeeemmmmoooovvvveeee(RWBoolean (*testFun)(const T*, void*),void* d);


     Removes and returns the first item for which the user-defined tester
     function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE, or nnnniiiillll if there is no such
     item.  The tester function must have the prototype:

                 RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              T*
          rrrreeeemmmmoooovvvveeeeAAAAtttt(size_t i);


     Removes and returns the item at index iiii.  The index iiii must be between
     zero and the number of items in the collection less one or an exception
     of type TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.

              T*
          rrrreeeemmmmoooovvvveeeeFFFFiiiirrrrsssstttt();


     Removes and returns the first item in the list, or nnnniiiillll if there are no
     items in the list.

              T*
          rrrreeeemmmmoooovvvveeeeLLLLaaaasssstttt();


     Removes and returns the last item in the list, or nnnniiiillll if there are no
     items in the list.



                                                                        PPPPaaaaggggeeee 6666






RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvDDDDlllliiiisssstttt((((3333CCCC++++++++))))



              T*
          rrrreeeemmmmoooovvvveeeeRRRReeeeffffeeeerrrreeeennnncccceeee(T* a);


     Removes and returns the item with address aaaa, or nnnniiiillll if there is no such
     item.

















































                                                                        PPPPaaaaggggeeee 7777